Crate winit

Winit allows you to build a window on as many platforms as possible.

Building a window

Before you can build a window, you first need to build an EventsLoop. This is done with the EventsLoop::new() function. Example:

use winit::EventsLoop;
let events_loop = EventsLoop::new();

Once this is done there are two ways to create a window:

• Calling Window::new(&events_loop).
• Calling let builder = WindowBuilder::new() then builder.build(&events_loop).

The first way is the simplest way and will give you default values for everything.

The second way allows you to customize the way your window will look and behave by modifying the fields of the WindowBuilder object before you create the window.

Events handling

Once a window has been created, it will generate events. For example whenever the user moves the window, resizes the window, moves the mouse, etc. an event is generated.

The events generated by a window can be retrieved from the EventsLoop the window was created with.

There are two ways to do so. The first is to call events_loop.poll_events(...), which will retrieve all the events pending on the windows and immediately return after no new event is available. You usually want to use this method in application that render continuously on the screen, such as video games.

use winit::{Event, WindowEvent};
use winit::dpi::LogicalSize;

loop {
    events_loop.poll_events(|event| {
        match event {
            Event::WindowEvent {
                event: WindowEvent::Resized(LogicalSize { width, height }),
                ..
            } => {
                println!("The window was resized to {}x{}", width, height);
            },
            _ => ()
        }
    });
}

The second way is to call events_loop.run_forever(...). As its name tells, it will run forever unless it is stopped by returning ControlFlow::Break.

use winit::{ControlFlow, Event, WindowEvent};

events_loop.run_forever(|event| {
    match event {
        Event::WindowEvent { event: WindowEvent::CloseRequested, .. } => {
            println!("The close button was pressed; stopping");
            ControlFlow::Break
        },
        _ => ControlFlow::Continue,
    }
});

If you use multiple windows, the WindowEvent event has a member named window_id. You can compare it with the value returned by the id() method of Window in order to know which window has received the event.

Drawing on the window

Winit doesn't provide any function that allows drawing on a window. However it allows you to retrieve the raw handle of the window (see the os module for that), which in turn allows you to create an OpenGL/Vulkan/DirectX/Metal/etc. context that will draw on the window.

Modules

dpi	DPI is important, so read the docs for this module if you don't want to be confused.
os	Contains traits with platform-specific methods in them.

Structs

AvailableMonitorsIter	An iterator for the list of available monitors.
DeviceId	Identifier of an input device.
EventsLoop	Provides a way to retrieve events from the system and from the windows that were registered to the events loop.
EventsLoopClosed	The error that is returned when an EventsLoopProxy attempts to wake up an EventsLoop that no longer exists.
EventsLoopProxy	Used to wake up the EventsLoop from another thread.
Icon	An icon used for the window titlebar, taskbar, etc.
KeyboardInput	Describes a keyboard input event.
ModifiersState	Represents the current state of the keyboard modifiers
MonitorId	Identifier for a monitor.
Touch	Represents touch event
Window	Represents a window.
WindowAttributes	Attributes to use when creating a window.
WindowBuilder	Object that allows you to build windows.
WindowId	Identifier of a window. Unique for each window.

Enums

BadIcon	An error produced when using Icon::from_rgba with invalid arguments.
ControlFlow	Returned by the user callback given to the EventsLoop::run_forever method.
CreationError	Error that can happen while creating a window or a headless renderer.
DeviceEvent	Represents raw hardware events that are not associated with any particular window.
ElementState	Describes the input state of a key.
Event	Describes a generic event.
MouseButton	Describes a button of a mouse controller.
MouseCursor	Describes the appearance of the mouse cursor.
MouseScrollDelta	Describes a difference in the mouse scroll wheel state.
TouchPhase	Describes touch-screen input state.
VirtualKeyCode	Symbolic name for a keyboard key.
WindowEvent	Describes an event from a Window.

Type Definitions

AxisId	Identifier for a specific analog axis on some device.
ButtonId	Identifier for a specific button on some device.
ScanCode	Hardware-dependent keyboard scan code.